/**
 * Category.java
 * 
 * FreeZzaph is free software; you can redistribute it
 * and/or modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 3 of
 * the License, or (at your option) any later version.
 *
 * FreeZzaph is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; see the file COPYING.
 */
package freezzaph.plugins;

import java.net.URL;

/**
 * <p>Identifies a category, typically this will be "Anal sex" or
 * "Hentai" or "Pregnant" or "Asian"... you get the picture.
 * 
 * <p>The name should be short, all lowercase, contain no whitespace
 * and no special characters. The method {@link #prettify(String) prettify()}
 * is a convenience method simply turning an ordinary string into
 * a legal name. It may be enough for most cases.
 * 
 * <p>The description should be a more descriptive name for the category.
 * Typically, this will be the non-prettified name of the category. If the
 * name is "analsex" then the description will most likely be "Anal sex".
 * 
 * <p>The filter is a regular expression that decides what file name extensions
 * to download for this category. The category provides URLs, and the main program
 * then uses the filter to decide which files to download from these URLs. Take a
 * look at the convenience filter strings for examples.
 * 
 * @author FreeZzaph
 */
public abstract class Category {
	
	/**
	 * Convenience filter string; provides a default way of
	 * downloading images.
	 */
	protected static final String pictureFilter = "jpe?g|jpe|jfif?|jif|gif|png";
	
	/**
	 * Convenience filter string; provides a default way of
	 * downloading videos.
	 */
	protected static final String movieFilter = "mpe?g|avi|rm|wmv|mkv|mov|qt|divx|flv|mp4|ps|ts|ogm";
	
	private String name;
	private String description;
	private String filter;
	
	/**
	 * Turns a string into a legal name string. Converts a string like
	 * "Fetish, Bizarre & Weird" into a more proper string, namely
	 * "fetish-bizarre-weird".
	 * 
	 * @param string the string to convert
	 * @return the converted string
	 */
	public static String prettify(String string) {
		String newString = string.toLowerCase().replaceAll("\\s+", "-");
		newString = newString.replaceAll("[^-A-Za-z0-9]", "");
		newString = newString.replaceAll("--", "-");
		return newString;
	}
	
	/**
	 * Construct a new Category with the given name, description
	 * and filter.
	 * 
	 * @param name the name of the Category. This should be short,
	 * all lowercase, contain no whitespace and no special characters.
	 * @param description the description of the Category. Should be
	 * a more descriptive name for the category. Typically, this will
	 * be the same as the name, but without the restrictions on case
	 * and whitespace. If the name is "analsex" then a decent value for
	 * description is "Anal sex".
	 * @param filter regular expression that lists file extensions
	 * that this category represents. The filter is only to contain
	 * the file extensions, such as "(tar.)?(g?z|bz2?)" to fetch
	 * archive types commonly used on Un*x systems.
	 */
	public Category(String name, String description, String filter) {
		this.name = name;
		this.description = description;
		this.filter = filter;
	}

	/**
	 * Returns the name of the category.
	 * 
	 * @return the name of the category.
	 */
	public String getName() {
		return name;
	}

	/**
	 * Returns the description of the category.
	 * 
	 * @return the description of the category.
	 */
	public String getDescription() {
		return description;
	}

	/**
	 * Returns the filter of the category.
	 * 
	 * @return the filter of the category.
	 */
	public String getFilter() {
		return filter;
	}
	
	/**
	 * <p>Return an array of URLs for the given category.
	 * 
	 * <p>The <code>start</code> parameter decides where in the list to start
	 * fetching URLs, for those sites that keep their entire list of URLs forever.
	 * Typically, the value 0 will fetch the most recent entries, and higher
	 * values will progressively head towards older entries. For sites that only
	 * keep a limited amount of links available at any given time, this value
	 * can be ignored.
	 * 
	 * <p>The <code>count</code> parameter denotes how many entries to fetch. If
	 * say <code>start</code> is set to 56 and <code>count</code> is set to 10,
	 * then the entries 56-66 will be fetched. A value of -1 means to let the
	 * plugin decide how many to fetch, will typically be a reasonable default
	 * value. The plugin <strong>must</strong> appropriately handle a value of -1
	 * for count.
	 *  
	 * @param start where in the list to start fetching entries.
	 * @param count how many entries to fetch. If set to -1, let the plugin decide.
	 * @return an array of URLs fetched using the given parameters.
	 */
	abstract public URL[] fetch(int start, int count);

}
